4 Navigation

The navigation commands are for making another todo file, category, or item the current one by moving point to it.² Since these commands are likely to be used frequently and repetitively, it is convenient for their key bindings to be single lower case keys, even for navigation commands applying to categories and files.

Two of the navigation commands were already mentioned in Todo Mode Entry Points:

t

Display another todo file in the selected window (todo-show). When you invoke this command in Todo mode, it prompts for a file name, which you can choose via minibuffer completion (like invoking todo-show with a prefix argument outside of Todo mode). If a buffer is already visiting that file, it displays its current category; if invoking t opens the file, it display its first category (by default; see the option todo-show-first for other possibilities).

j

Display another todo category in the selected window (todo-jump-to-category). When you invoke this command, it prompts for a category name, which you can choose via minibuffer completion. The candidates for completion include the categories in the current todo file as well as those in the files listed in the option todo-category-completions-files. If you type RET without choosing a category, the current category of the current todo file is automatically selected (this can be a useful shortcut when you invoke todo-jump-to-category outside of Todo mode). If you type the name of a non-existing category, you can add this to the file as a new category and jump to it. If you invoke this command with a prefix argument, it first you prompts for which todo file to jump to (which you can also choose with minibuffer completion) and then for which category from that file; in this case, completion is only against the categories in the selected file.

It is also convenient to navigate back and forth sequentially between the categories of a single todo file. The categories of a todo file are numbered consecutively starting with ‘1’.³ The current category’s number and name appear in the mode line.

f

Move point to the first item of the category numerically directly following the current category (todo-forward-category).

b

Move point to the first item of the category numerically directly preceding the current category (todo-backward-category).

With f and b you can cycle through the categories, so for example, if the last category is current and you type f, then the first category becomes current.

You can also navigate between the items in the current category:

n

Move point down to the next item below the current one (i.e., to the item with the next lower priority) (todo-next-item).

p

Move point up to the item directly above the current one (i.e., to the item with the next higher priority) (todo-previous-item).

These commands also accept a positive numeric prefix argument; e.g., typing 5 n or 5 p navigates in one step to the item five items lower or higher than the current one.

Navigation to other types of Todo files is discussed in the relevant sections below.